Inside Macintosh: OpenDoc Programmer's Guide / Part 2 - Programming

Chapter 6 - Windows and Menus

Controls

This section discusses what kinds of controls you can use, how you can construct them, and how to handle events within controls. It also discusses two specific issues for palettes: how to share them among instances of your part, and how to use them to embed parts within your part.

Design Issues for Controls

Controls in OpenDoc have the same function as in conventional applications: they are graphical objects that allow the user to interact with and manipulate documents in a variety of ways. However, there are some differences:

• In a conventional application, controls typically apply to the entire document. They are always present unless dismissed explicitly. In an OpenDoc document, however, each part may have its own set of controls, and thus controls can appear and disappear rapidly as the user edits. This rapid change can be irritating if it is not carefully managed.
• In a conventional application, finding the space in which to display a control may be less of a consideration than in OpenDoc. It may be a challenge for small embedded parts to find sufficient space to display rulers, scroll bars, and palettes.
• In OpenDoc, you can construct controls as independent parts, assemblages of parts, different frames of a single part, or content elements of a part. You thus have more flexibility in constructing user-interface elements than is possible with conventional applications.
• OpenDoc controls can have attached scripts or can communicate with each other, or with other parts, using the OpenDoc extension mechanism. Thus, your OpenDoc controls can be far more integrated and context-sensitive than standard controls.

Standard types of controls you might wish to include with your parts include

• buttons, radio buttons, and checkboxes
• scroll bars, sliders, or other gauges
• pop-up menus
• rulers
• tool bars
• status bars
• palettes

Rulers usually reflect some settings of the current selection context and contain controls that allow the user to change these settings. Tool bars are like rulers, but they often trigger actions instead of changing settings. Status bars display the progress of some long-running operation or suggest actions to users.

In conventional applications, rulers, tool bars, and status bars commonly occupy the margins of the window. In an OpenDoc document, controls can appear within the frame they apply to, or in separate frames outside the frame they apply to.

A ruler for a text part, for example, can be an additional frame associated with the part. Events in the ruler are handled by the part's editor. Alternatively, the ruler may be its own part with its own editor. In this case, the text part editor must maintain a reference to the ruler part and be able to communicate with it through semantic events or some other extension mechanism.

A ruler that is a separate part can have its own embedded parts, such as buttons. The ruler part must then be able to communicate with its embedded controls as well as with the part that it services.

Palettes often contain editing tools but can also contain choices for object attributes such as color or line width. Palettes commonly float freely beside or over the document, although they can also be fixed at the window margins. Palettes might also be pop-up, pull-down, or tear-off menus.

If all parts in a document can communicate with each other, they can coordinate the drawing and hiding of palettes or other controls, to avoid irritating the user. For example, all parts in a document can share a single palette. The various parts negotiate for space within the palette, and they draw or erase only those tools that change as the active part changes.

Handling Events in Controls

How you handle events in a control depends on how you design the control.

• If a control like a ruler is within the active frame, it might not have its own frame, and the active part editor handles any events in the ruler.
• If a control has its own frame, it might be another display frame of the active part. In this case also, the active part editor handles the event in the control.
• If a control is a separate part, its own part editor handles the event and updates the state of the part. Updates might trigger scripts or calls to the extension interfaces of other parts. Likewise, the part itself can receive queries from other part editors, in the form of semantic events or calls to its extension interface.

Sharing Palettes and Utility Windows

The user-interface guidelines presented in the section "Palettes and Tool Bars" state that you should hide any visible palettes, modeless dialog boxes, or other utility windows when your part becomes inactive or its document closes, and restore them--in the same positions--when the part becomes active once again or the document reopens. In addition, if your part editor maintains multiple parts in a document and the active state switches from one to another of them, any visible utility windows that apply to both parts should remain steadily visible, without any flicker caused by hiding and immediate restoring.

One way to implement this behavior for a utility window is to follow, in general, steps such as these:

• Make the window globally accessible to your parts by keeping its reference and its state in an object that each of your parts acquires on initialization and releases on closing.
• Have the global object create the window in a normal manner the first time it is to be displayed. When the user closes the window, the global object can simply hide it by calling its Hide method. If the user subsequently needs to redisplay the window, the global object can reshow it by calling its Show method.
• When your part relinquishes the selection focus, its CommitRelinquishFocus method can check whether the part that is receiving the focus also belongs to your part editor and has a presentation that uses the same utility window. There are a number of ways to check this, such as by examining the presentation, part info, or even the part kind associated with the newly active frame.
• When your part acquires the selection focus, it notifies the global object of that fact. The global object in turn calls the ChangePart and SetSourceFrame methods of the utility window's frame to assign the new part and frame to the utility window. The new part can then adjust the content of the utility window if needed, and also show or hide other palettes or dialog boxes.

Using a Tool Palette to Embed Parts

An example of an OpenDoc-specific use of controls is to allow the user to embed parts by selecting items from a palette. Using a palette in this way, your part can create embedded parts from scratch rather than by reading in existing part data.

Your part can provide a palette, menu, or dialog box from which the user selects an item that specifies a part kind. As in many conventional applications, your palette could display a set of tools to the user--drawing tools, painting tools, text tools, and so on. In this case, however, selecting an item from the palette actually means that a new part of that kind is to be embedded in your part. The section "Creating Parts From Tool Palettes" describes interface guidelines for presenting such a palette to the user.

The items could represent existing stationery documents in the user's system, or they could simply represent individual part kinds for which editors exist. If you are creating parts from scratch, follow steps such as these once the user has made a selection from your palette:

1. Create the new part by calling your draft's CreatePart method, passing it the part kind that the user selected.
2. Call the new part's Externalize method (see "The Externalize Method") so that the part can create and write initial data to the properties in its storage unit.
3. Create a new embedded frame for the part, as described in "Creating a New Embedded Frame".
4. Give the new frame the proper link status, as described in "Frame Link Status".
5. If the new frame is visible, assign facets to it, as described in the section "Adding a Facet".
6. Notify your containing part and your draft that there has been a change to your part's content; see "Making Content Changes Known"

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help